Books

Books are used to organize large libraries of songs into collections.

List books

URL	/api/<auth_token>/books
Method	GET
Version	1.0

Description

Lists books in your OnSong library.

Path arguments

Name	Type	Description	Required
auth_token	string	The authentication token used to authenticate the request.	Required

Query arguments

Options for searching are passed via the query string as follows:

/api/<auth_token>/books?q=sample&sort=title

Name	Type	Description	Required
q	string	The query to look up books by title	Optional
sort	string	The sort method to use when returning sets. Options include: title sorts books by title. Default. orderIndex sorts books by their set position. quantity sorts books by the number of songs contained within.	Optional
descending	boolean	Determines if sets should be returned in descending order. The default order is set by the sort method.	Optional
limit	number	Limits the number of results returned. Default is 100.	Optional
start	number	Offsets the start of returned results to be used for paging through results. Default is 0.	Optional

Response

Returns a list of books by providing book ID and name.

Response example

{
  "count" : 1,
  "results" : [
    {
      "ID" : "Sample Book",
      "name" : "Sample Book"
    }
  ],
  "attributes" : {
    "q" : "sample",
    "sort" : "title"
  }
}

Create book

URL	/api/<auth_token>/books
Method	PUT
Version	1.0

Description

Creates a new book in your library.

Path arguments

Name	Type	Description	Required
auth_token	string	The authentication token used to authenticate the request.	Required

Body arguments

The body of the request should be a Book Object. The name property is required and any ID property will be ignored.

Response

One of two results will be returned:

Name	Type	Description
success	object	The operation was successful and basic book information is returned.
error	string	The operation has failed and text indicating the error is returned.

Response example

The following is an example of a successful creation:

{
  "success" : {
    "ID" : "Jam Group", 
    "name" : "Jam Group"
  }
}

The following is an example of a failed operation with a 500 status code:

{
  "error" : "Name is required"
}

View book information

URL	/api/<auth_token>/books/<book_identifier>
Method	GET
Version	1.0

Description

Retrieves book information from the OnSong library.

Path arguments

Name	Type	Description	Required
auth_token	string	The authentication token used to authenticate the request.	Required
book_identifier	string	The name of the book to be retrieved. This can be the name of the book to be retrieved or the term "current" to use the currently active book.	Required

Query arguments

Name	Type	Description	Required
show_songs	boolean	Determines if songs should be displayed using the "songs" property.	Optional

Response

The response includes a Book Object. The songs property is omitted unless the show_songs parameter is turned on.

Response example

{
    "ID": "Jam Group",
    "orderDirection": 0,
    "name": "Jam Group",
    "orderMethod": "added",
    "songs": [
        {
            "artist": "The Beatles",
            "favoriteColor": null,
            "title": "A Hard Day's Night",
            "favorite": 0,
            "usefile": false,
            "key": null,
            "ID": "947E9C9A-D01D-43B1-BE09-CD3BB90BF995"
        },
        {
            "artist": "Hooters",
            "favoriteColor": null,
            "title": "And We Danced",
            "favorite": 0,
            "usefile": false,
            "key": null,
            "ID": "2F0021FE-60DD-41A6-8354-CEBB9B99B95B"
        }
    ]
}

Update book

URL	/api/<auth_token>/books/<set_identifier>
Method	POST
Version	1.0

Description

Updates a book in your library.

Path arguments

Name	Type	Description	Required
auth_token	string	The authentication token used to authenticate the request.	Required

Body arguments

The body must be a valid Book Object. Please note that if arguments are not provided, no changes will be made to those property. When setting the songs property, either an array of song identifiers or song objects can be used. This will overwrite any existing songs and set the songs of the book to the list of songs passed into this property.

Response

Returns an array of status updates for each property that has been updated.

Name	Type	Description
success	object	The operation was successful and basic set information is returned.
error	string	The operation has failed and text indicating the error is returned.

Response example

The following is an example of a successful update:

[
  {
    "success" : { "/books/837BB846-F374-4369-86ED-2A1A08EE131B/name" : "Party Songs" }
  },
  {
    "success" : { "/books/837BB846-F374-4369-86ED-2A1A08EE131B/songs" : [ "837BB846-F374-4369-86FF-2A1A08EE131B", "837BB846-F374-4369-86FE-2A1A08EE131B" ] }
  }
]

The following is an example of a failed operation with a 500 status code:

{
  "error" : "Input must be a dictionary object"
}

Delete book

URL	/api/<auth_token>/books/<book_identifier>
Method	DELETE
Version	1.0

Description

Deletes a book from your library.

Path arguments

Name	Type	Description	Required
auth_token	string	The authentication token used to authenticate the request.	Required
book_identifier	string	The name of the book to be deleted. This can be the name of the book to be retrieved or the term "current" to use the currently active book.	Required

Response

Name	Type	Description
success	object	The operation was successful and basic set information is returned.
error	string	The operation has failed and text indicating the error is returned.

Response example

The following is an example of a successful deletion:

{
  "success" : { "ID" : "837BB846-F374-4369-86ED-2A1A08EE131B", "name" : "Deleted Book" }
}

The following is an example of a failed operation with a 500 status code:

{
  "error" : "No book found"
}

List songs

URL	/api/<auth_token>/books/<book_identifier>/songs
Method	GET
Version	1.0

Description

Lists songs contains in a book.

Path arguments

Name	Type	Description	Required
auth_token	string	The authentication token used to authenticate the request.	Required
book_identifier	string	The name of the book to which songs will be returned. This can be the name of the book to be retrieved or the term "current" to use the currently active book.	Required

Query arguments

Options for searching are passed via the query string as follows:

/api/<auth_token>/books/<book_identifier>/songs?limit=10&sort=title

Name	Type	Description	Required
q	string	The keyword query to look up songs. The API searches song title, artist, keywords and lyrics e.g. "love"	Optional
title	string	The song title (full or partial) of the songs to retrieve e.g. "Rambl"	Optional
artist	string	The artist (full or partial) of the songs to retrieve e.g. "Beatles"	Optional
key	string	The key of the songs to retrieve e.g. "Am"	Optional
topic	string	The topic/keyword of the songs to retrieve e.g. "Country"	Optional
sort	string	The sort method to use when returning songs. Options include: title sorts the songs by song title. Default. artist sorts the songs by the artist. favorite sorts the songs is the song is marked as a favorite. Defaults to descending order. added sorts the songs by the date the song was added. Defaults to descending order. updated sorts the songs by the date the song was updated. Defaults to descending order. number sorts the songs by the song number. random sorts the songs in random order. orderIndex sorts the songs by their order in a set. lastPlayed sorts the songs by date they were last played. Defaults to descending order. mostPopular sorts the songs by how often it has been placed in a set. Defaults to descending order.	Optional
descending	boolean	Determines if songs should be returned in descending order. The default order is set by the sort method.	Optional
limit	number	Limits the number of results returned. Default is 100.	Optional
start	number	Offsets the start of returned results to be used for paging through results. Default is 0.	Optional

Response

Returns a list of songs in the book including the song's unique identifier, title and other basic information.

Name	Type	Description
count	int	The total number of results that are returned, independent of limit and start.
results	array	Returns a list of song objects which include the song ID, title, artist, key, key, favorite and usefile. ID The unique identifier of the song. title The title of the song. artist The artist or byline information of the song. key The current key of the song. favorite Determines if the song has been favorited. usefile Determines if the external file should be used for displaying the song.
attributes	object	Contains the query attributes that were passed.

Response example

{
  "count" : 4,
  "results" : [
    {
      "ID" : "54AD9D08-69F0-49E7-9086-247B9F70457F",
      "title" : "How He Loves",
      "favorite" : 0,
      "usefile" : false,
      "key" : "C",
      "artist" : "David Crowder Band"
    },
    {
      "ID" : "D3368162-FBC0-4D2F-B2BA-709ADE2DEB9A",
      "title" : "One Thing Remains",
      "favorite" : 0,
      "usefile" : false,
      "key" : "G",
      "artist" : "Jesus Culture"
    }
  ],
  "attributes" : {
    "q" : "love",
    "start" : "1",
    "limit" : "2"
  }
}

Add songs

URL	/api/<auth_token>/books/<book_identifier> or /api/<auth_token>/books/<book_identifier>/songs
Method	PUT
Version	1.0

Description

Add songs to a book.

Path arguments

Name	Type	Description	Required
auth_token	string	The authentication token used to authenticate the request.	Required
book_identifier	string	The name of the book to which songs will be added. This can be the name of the book to be retrieved or the term "current" to use the currently active book.	Required

Body arguments

The body can be an array of song identifiers or song objects that contain an ID property. Alternately, you can express this as a dictionary that contains a songs property or a single song identifier string.

Response

Name	Type	Description
success	object	The operation was successful and lists the songs that were added to the book.
error	string	The operation has failed and text indicating the error is returned.

Response example

The following is an example of a song being a successful added to the book:

{
    "success": {
        "/books/Jam Group/songs": [
            "C43DC77D-68BF-4BFE-8A56-BCB51CF73AC5"
        ]
    }
}

The following is an example of a failed operation with a 500 status code:

{
  "error" : "No book found"
}

Remove songs

URL	/api/<auth_token>/books/<book_identifier>/songs
Method	DELETE
Version	1.0

Description

Removes songs from a book.

Path arguments

Name	Type	Description	Required
auth_token	string	The authentication token used to authenticate the request.	Required
book_identifier	string	The name of the book from which songs will be removed. This can be the name of the book to be retrieved or the term "current" to use the currently active book.	Required

Body arguments

The body can be an array of song identifiers or song objects that contain an ID property. Alternately, you can express this as a dictionary that contains a songs property or a single song identifier string.

Response

Name	Type	Description
success	object	The operation was successful and lists the songs that were removed from the book.
error	string	The operation has failed and text indicating the error is returned.

Response example

The following is an example of a song being a successful removed from the book:

{
    "success": {
        "/books/Jam Group/songs": [
            "C43DC77D-68BF-4BFE-8A56-BCB51CF73AC5"
        ]
    }
}

The following is an example of a failed operation with a 500 status code:

{
  "error" : "No book found"
}